home *** CD-ROM | disk | FTP | other *** search
- CVS 1.11.2 AmigaOS/MorphOS port (09 November 2002)
- ==================================================
-
- Introduction
- ------------
- This is a somewhat rough port of GNU CVS 1.11.2, a version control system,
- which allows you to keep old versions of files (usually source code), keep a
- log of who, when, and why changes occurred, etc., like RCS or SCCS. It handles
- multiple developers, multiple directories, triggers to enable/log/control
- various operations, and can work over a wide area network. The following tasks
- are not included; they can be done in conjunction with CVS but will tend to
- require some script-writing and software other than CVS: bug-tracking, build
- management (that is, make and make-like tools), and automated testing. (Quoted
- from the CVS documentation.)
-
- I call this a 'rough port' since it is not as polished as, say Heinz Wrobel's
- excellent 'RCS' port. It does what it needs to do, but a few features are
- sorely lacking, such as full support for Amiga file protection bits. On the other
- hand, however, you get everything, and perhaps more, you got with the previous
- Amiga ports of CVS: this port does not require 'ixemul.library' to work and it
- does not require an RCS installation because it is completely self contained.
- The port would also probably win a price as the largest 'pure' executable; it
- can be made resident.
-
-
- What's in this package?
- -----------------------
- This distribution contains the Amiga port, the Amiga specific source code and
- most of the original GNU CVS 1.11.2 distribution. 'Most' in this case means
- that only the original source code has been omitted in order to keep the
- distribution archive small; the documentation and support files are all
- provided. The original source code can be downloaded from the Internet at
- 'ftp://ftp.cvshome.org/pub/cvs-1.11.2/cvs-1.11.2.tar.gz'. I have added two
- more files which are converted from the original Unix man pages, namely
- 'cvs.1.man' and 'cvs.5.man' whose sources can be found in the
- 'cvs-1.11.2/man' directory.
-
-
- Installation; the easy part
- ---------------------------
- Almost everything you need to get CVS up and running is contained in the
- archive which also includes the 'README.AMIGA' file you are currently reading.
- And that means the 'cvs' executable. You will also need a working
- 'queue-handler' (the one that ships with Workbench 3.1 and beyond is,
- unfortunately, broken) which can be found on Aminet (you can find the archive
- at 'http://us.aminet.net/pub/aminet/util/sys/HWGQueue.lha'). A TCP/IP stack
- like Miami or AmiTCP is supported but not strictly required: you can perfectly
- well keep your CVS repository on your local machine. Since CVS may ask you to
- edit the log entries associated with the files to store, you may want to
- configure the 'EDITOR' environment variable. Last, but not least, you must set
- up an environment variable which allows CVS to associate you with the changes
- you made; this should be the 'USER', 'LOGUSER' or 'USERNAME' variable.
-
- Most importantly, this port requires Kickstart 2.04 or higher.
-
- Here is how you could set up CVS on your machine. We start by creating two
- drawers on the 'Work:' volume:
-
- MakeDir Work:CVS-Root
- MakeDir Work:CVS-Home
-
- Next, we add two lines to the 'S:User-Startup' file:
-
- Assign CVSHOME: Work:CVS-Home
- Path CVSHOME: Add
-
- The CVS program will need to be copied:
-
- Copy cvs Work:CVS-Home CLONE
-
- And the path to the CVS repository needs to be set:
-
- SetEnv CVSROOT :local:Work:CVS-Root
- Copy ENV:CVSROOT ENVARC:
-
- Two environment variables need to be set up. Most importantly, CVS will need
- your ID to write it into the log and revision files it creates. The Amiga port
- will query three environment variables for that information, in the following
- order: 'USER', 'LOGUSER' and 'USERNAME'. This means if the variable 'USER' is
- not set, it will proceed to check whether 'LOGUSER' is set, and so forth. You
- may have already configured these variables, but if you haven't, I suggest you
- set up the 'LOGUSER' variable, like this:
-
- SetEnv LOGUSER <Your ID here>
- Copy ENV:LOGUSER ENVARC:
-
- Note that <Your ID here> should be replaced by a mnemonic, nick name or short
- name that must not contain any blank space characters. This means for example
- that "Fred Flintstone" will not work, but "Fred_Flintstone" will.
-
- You may want to configure the 'EDITOR' environment variable to invoke your
- preferred text editor when CVS requests that log messages are added for an
- update. If this variable is not set, CVS will default to invoke the 'Ed'
- editor. This can be problematic if you have installed 'CygnusEd' whose 'Ed'
- program detaches from the Shell that invoked it. When CVS invokes the editor,
- it expects it to return only when the user has finished editing the respective
- file. Here is an example configuration for CygnusEd:
-
- SetEnv EDITOR Ed -keepio
-
- And here is one for TurboText:
-
- SetEnv EDITOR TTX WAIT
-
- Don't forget to save the environment variable setting to make it permanent,
- like this:
-
- Copy ENV:EDITOR ENVARC:
-
- Finally, install the 'queue-handler' from Aminet and reboot your machine. When
- the system is again up and running, initialize the CVS repository like this:
-
- cvs init
-
- And that's all. Well, maybe you want to add a few default options to the
- configuration file CVS reads upon startup. That file should be placed in the
- 'CVSHOME:' directory and called '.cvsrc'.
-
-
- Networked operation and SSH
- ---------------------------
- This CVS port includes built-in remote shell (rsh) and secure shell (ssh)
- client code, which allows you to exchange files with networked, non-local CVS
- repositories. To use a remote repository, you will need to change the name of
- the CVS root directory. For a local repository, you would use the following
- commands to set it up, like this:
-
- SetEnv CVSROOT :local:Work:CVS-Root
- Copy ENV:CVSROOT ENVARC:
-
- But if the repository were on a remote machine, you would use something like
- this:
-
- SetEnv CVSROOT :server:login@host:/usr/local/cvsroot
- Copy ENV:CVSROOT ENVARC:
-
- In that example, you would replace 'login' with your account name on the
- networked machine called 'host'; the '/usr/local/cvsroot' refers to the fully
- qualified name of the CVS root directory. Note that for this to work, you need
- to have a shell login account on the remote machine, and that machine must be
- configured to allow for remote shell login. Because the remote shell login is
- rather risky and insecure, most sites will have it disabled. Bad luck, but
- there is an alternative: secure shell. This feature allows you to connect to a
- remote repository as with a remote shell login, except that the connection is
- made in a much more secure fashion using encrypted data channels. This process
- requires that you have a login password handy, for which the CVS port will
- prompt you before it connects to the remote. To activate the secure shell
- feature, you would set an environment variable, like this:
-
- SetEnv CVS_RSH ssh
-
- This will cause the built-in secure shell (ssh) client to be used in place of
- the remote shell (rsh) client. The secure shell client implementation is a
- stripped down, simplified version of the real thing, the full-blown version,
- which supports more different and more secure encryption algorithms. What this
- version can do is just about the bare minimum, which means that it supports
- only two block cipher algorithms ('Triple DES' and 'Blowfish') and that the
- initial public key exchange is not as fast as it could be. It supports only
- version 1.5 of the secure shell protocol.
-
- By default, the ssh client will resort to 'Triple DES' for encryption and
- decryption, which is not particularly fast. To choose the 'Blowfish' algorithm
- instead (which runs faster than 'Triple DES'), use the following environment
- variable:
-
- SetEnv CVS_SSH_CIPHER blowfish
-
- Not all secure shell server implementations support the 'Blowfish' algorithm,
- but all servers are required to support 'Triple DES'. Thus, if you cannot
- connect to a server which aborts the protocol negotiation, it may be that it
- does not understand the choice of the encryption algorithm.
-
- CAUTION: The majority of the CVS documentation I know recommends to use the
- keyword ':ext:' in place of ':server:' for communicating with a
- networked CVS installation -- this will *NOT* work with this Amiga
- port. What does work are the built-in rsh and ssh clients, and these
- require that you use the ':server:' keyword when specifying the name
- of the CVS root directory. Therefore the :ext: method is disabled
- in this port!
-
- By default, the SSH client will attempt to connect to the server on port 22.
- This is not always desirable, especially for custom SSH configurations. You
- can override this default choice of the port number using yet another
- environment variable, like this:
-
- SetEnv CVS_SSH_PORT 33194
-
- By default the built-in ssh client will prompt you to enter the password to
- authenticate with the remote server. By public request, a special feature was
- added to this CVS port which will cause server name, login and password to be
- stored in a local file for use with ssh.
-
- If you want to use this feature you have would set up the following
- environment variable:
-
- SetEnv CVS_SSH_PASSFILE CVSHOME:.sshpass
-
- We do not recommend that you use this feature because it compromises system
- security. You may want to use this feature only if you do not care about
- security and are prepared to face the consequences. We suggest that you store
- the ssh password file in a place different from the one you keep the passwords
- used by the :pserver: access method in. Do not mix the two files; undefined
- CVS behaviour may result.
-
- Last but not least, a word on data compression. The SSH specification allows
- for data to be compressed before it is encrypted. This functionality is not
- implemented in the reduced SSH implementation which is part of this Amiga CVS
- port. This sounds like a disadvantage, but it need not to be. In fact, CVS can
- use data compression for data exchange, and the SSH layer on top of it could
- not have compressed this data any further. That's entropy for you...
-
-
- Usage
- -----
- I personally found the default CVS documentation to be rather confusing. If
- you don't know rather well what CVS is good for, then the examples, the
- terminology, all this doesn't seem to make great sense. My introduction to CVS
- followed with Karl Fogel's book "Open Source Development with CVS" which
- describes in compact form what CVS is and how it may be used. I suggest that
- you consult the book (portions of which are available from 'www.coriolis.com')
- and/or the CVS documentation (which has been included with this archive in the
- 'cvs-1.11.2/doc' drawer) for hints and ideas on how to use the program. I would
- definitely not recommend that you spend any money on the CVS pocket reference
- manual written by Gregor N. Purdy, published by O'Reilly until *after* you
- have read an introductory book like Karl Fogel's. By its very nature, even a
- good pocket reference manual can only refresh your memory on concepts you have
- learned before -- if there is nothing to be refreshed in the first place, it
- will not be of any help to you.
-
- What many people fail to realize and what keeps them from using CVS in place
- of the revision control system they have used for years is that you do not
- need a networked CVS repository in order to use CVS. A local repository will
- do. In fact, I switched over most of my current software development projects
- to use a single local repository after I realized that CVS does much better
- what I had previously used RCS for.
-
- Further documentation and information CVS can be found on the CVS home page:
-
- http://www.cvshome.org/
-
- For a good tutorial have a look at:
-
- http://cvsbook.red-bean.com/cvsbook.html
-
-
- Notes on the implementation
- ---------------------------
- The Amiga port implements only the client side of the CVS system. This means
- that you can check out projects on remote servers but your local Amiga cannot
- be a CVS server itself. This feature was omitted deliberately since I could
- not find a safe and useful way to make CVS server mode work on the Amiga.
- AmigaOS is not a server operating system and shoehorning the code to make it
- work somehow would not have helped. If you need a CVS server, try a dedicated
- solution using, for example, 'NetBSD'. The Amiga port can communicate with the
- server using the remote shell (rsh) and secure shell (ssh) protocols, and I
- have verified that the process works reasonably well with, for example, the
- public 'Samba' CVS repository.
-
- CVS does not have a very sophisticated porting layer. Its file name semantics
- all stem from the Unix world and the 'OS/2', 'VMS' and 'Windows NT' ports
- merely resort to flipping slashes in file names, if necessary, when it comes
- to make a name fit the local system's semantics. I had to find a similar way
- to make the semantics work on the Amiga. What I did was to add a translation
- service in the Amiga specific code which knows how to translate names like '.'
- or '..'. But that's where it ends. Any more sophisticated naming schemes like
- 'foo/.././bar' may fail to translate properly. But then, those complex
- patterns should be pretty rare anyway.
-
- Unlike Heinz Wrobel's excellent 'RCS' port, this CVS port does not preserve
- Amiga file protection bits for files checked in. When you check in a project
- and check it out again, all file and directory protection bits will default to
- 'rwed', losing the 'archived', 'pure' and 'script' bits.
-
- The Amiga port will expand wild card patterns for file and directory names
- specified as command line parameters, such as "#?.c". The wild card pattern
- syntax is that of AmigaDOS. It is *not* the syntax of the standard regular
- expressions other GNU tools will use.
-
- You can access remote CVS repositories by means of a properly configured
- TCP/IP stack. This port requires that the stack complies to the AmiTCP V3 API
- definition, which all modern Amiga TCP/IP stacks do. It does not work with the
- INet-225 TCP/IP stack, though.
-
- When CVS resorts to calling external programs, a working 'PIPE:' device is
- required, which is not yet part of the AmigaOS Workbench distribution. Do not
- underestimate this. The program will fail or behave erratically without a
- working 'PIPE:' device. It is strongly recommended to download a working
- 'queue-handler', such as from Aminet.
-
- The source code for the Amiga port is included in this distribution. All you
- need to know before you can recompile this CVS port is described in the file
- 'README.SRC' which you can find in the 'source' directory.
-
- This is a 'single user' CVS port. There is just one single home directory
- (referred to as 'CVSHOME:') and your login name and ID are assumed to be the
- same (set in the 'USER', 'LOGUSER' or 'USERNAME' environment variables).
-
- There is no 'cvsbug' shell script or program included with this port.
-
-
- Known problems and issues
- -------------------------
-
- 1) Problems with time zones
-
- This port completely ignores the "ENVARC:TZ" time zone variable and uses your
- locale time zone configuration instead. While this should normally be the most
- transparent solution, daylight savings time is not taken into account. You may
- have to change your locale preferences accordingly.
-
- 2) File names longer than supported by the file system
-
- Another issue that can produce problems while working with CVS on the Amiga
- involves remote repositories (:pserver: or :server: method) which contain
- files and directories whose names are longer than the Amiga file system allows
- for. These names will be truncated when the respective files and directories
- are checked out, which has the unpleasant effect that you may not be able to
- check the files in again.
-
- 3) .cvspass error message with :pserver:
-
- If you use the :pserver: method with CVS a message like the following can
- appear:
-
- --- cut here ---
- DH0: > cvs login
- Logging in to :pserver:damato@linux:2401/data/cvsroot/amiga
- CVS password:
- cvs login: failed to open CVSHOME:.cvspass for reading: No such file or directory
- cvs [login aborted]: fatal error: exiting
- --- cut here ---
-
- The solution for this problem is quite simple. Just create an empty ".cvspass"
- file in your CVSHOME: directory (e.g. "Echo >CVSHOME:.cvspass noline") and
- next time CVS will use this file to store the passwords. This is normal CVS
- behaviour like in other ports.
-
-
- Contacting the authors
- ----------------------
- If you have any further questions on this port, feel free to contact us:
-
- Olaf Barthel
- Gneisenaustr. 43
- D-31275 Lehrte
- Federal Republic of Germany
-
- olsen@sourcery.han.de
-
- Jens Langner
- Lannerstrasse 1
- D-01219 Dresden
- Federal Republic of Germany
-
- Jens.Langner@light-speed.de
-